URI

A #SoupURI represents a (parsed) URI. #SoupURI supports RFC 3986 (URI Generic Syntax), and can parse any valid URI. However, libsoup only uses "http" and "https" URIs internally; You can use SOUP_URI_VALID_FOR_HTTP() to test if a #SoupURI is a valid HTTP URI.

@scheme will always be set in any URI. It is an interned string and is always all lowercase. (If you parse a URI with a non-lowercase scheme, it will be converted to lowercase.) The macros %SOUP_URI_SCHEME_HTTP and %SOUP_URI_SCHEME_HTTPS provide the interned values for "http" and "https" and can be compared against URI @scheme values.

@user and @password are parsed as defined in the older URI specs (ie, separated by a colon; RFC 3986 only talks about a single "userinfo" field). Note that @password is not included in the output of soup_uri_to_string(). libsoup does not normally use these fields; authentication is handled via #SoupSession signals.

@host contains the hostname, and @port the port specified in the URI. If the URI doesn't contain a hostname, @host will be %NULL, and if it doesn't specify a port, @port may be 0. However, for "http" and "https" URIs, @host is guaranteed to be non-%NULL (trying to parse an http URI with no @host will return %NULL), and @port will always be non-0 (because libsoup knows the default value to use when it is not specified in the URI).

@path is always non-%NULL. For http/https URIs, @path will never be an empty string either; if the input URI has no path, the parsed #SoupURI will have a @path of "/".

@query and @fragment are optional for all URI types. soup_form_decode() may be useful for parsing @query.

Note that @path, @query, and @fragment may contain %-encoded characters. soup_uri_new() calls soup_uri_normalize() on them, but not soup_uri_decode(). This is necessary to ensure that soup_uri_to_string() will generate a URI that has exactly the same meaning as the original. (In theory, #SoupURI should leave @user, @password, and @host partially-encoded as well, but this would be more annoying than useful.)

final

class URI {

SoupURI* soupURI;

bool ownedRef;

SoupURI* getURIStruct(bool transferOwnership);

void* getStruct();

this(SoupURI* soupURI, bool ownedRef);

string scheme [@property getter];

string scheme [@property setter];

string user [@property getter];

string user [@property setter];

string password [@property getter];

string password [@property setter];

string host [@property getter];

string host [@property setter];

uint port [@property getter];

uint port [@property setter];

string path [@property getter];

string path [@property setter];

string query [@property getter];

string query [@property setter];

string fragment [@property getter];

string fragment [@property setter];

static GType getType();

this(string uriString);

this(URI base, string uriString);

URI copyHost();

bool equal(URI uri2);

string getFragment();

string getHost();

string getPassword();

string getPath();

uint getPort();

string getQuery();

string getScheme();

string getUser();

bool hostEqual(URI v2);

uint hostHash();

void setFragment(string fragment);

void setHost(string host);

void setPassword(string password);

void setPath(string path);

void setPort(uint port);

void setQuery(string query);

void setQueryFromForm(HashTable form);

void setScheme(string scheme);

void setUser(string user);

string toString(bool justPathAndQuery);

bool usesDefaultPort();

static string decode(string part);

static string encode(string part, string escapeExtra);

static string normalize(string part, string unescapeExtra);

}

Constructors

this this(SoupURI* soupURI, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(string uriString): Parses an absolute URI.
this this(URI base, string uriString): Parses @uri_string relative to @base.

Destructor

~this ~this(): Undocumented in source.

Members

Functions

copy URI copy(): Copies @uri
copyHost URI copyHost(): Makes a copy of @uri, considering only the protocol, host, and port
equal bool equal(URI uri2): Tests whether or not @uri1 and @uri2 are equal in all parts
free void free(): Frees @uri.
getFragment string getFragment(): Gets @uri's fragment.
getHost string getHost(): Gets @uri's host.
getPassword string getPassword(): Gets @uri's password.
getPath string getPath(): Gets @uri's path.
getPort uint getPort(): Gets @uri's port.
getQuery string getQuery(): Gets @uri's query.
getScheme string getScheme(): Gets @uri's scheme.
getStruct void* getStruct(): the main Gtk struct as a void*
getURIStruct SoupURI* getURIStruct(bool transferOwnership): Get the main Gtk struct
getUser string getUser(): Gets @uri's user.
hostEqual bool hostEqual(URI v2): Compares @v1 and @v2, considering only the scheme, host, and port.
hostHash uint hostHash(): Hashes @key, considering only the scheme, host, and port.
setFragment void setFragment(string fragment): Sets @uri's fragment to @fragment.
setHost void setHost(string host): Sets @uri's host to @host.
setPassword void setPassword(string password): Sets @uri's password to @password.
setPath void setPath(string path): Sets @uri's path to @path.
setPort void setPort(uint port): Sets @uri's port to @port. If @port is 0, @uri will not have an explicitly-specified port.
setQuery void setQuery(string query): Sets @uri's query to @query.
setQueryFromForm void setQueryFromForm(HashTable form): Sets @uri's query to the result of encoding @form according to the HTML form rules. See soup_form_encode_hash() for more information.
setScheme void setScheme(string scheme): Sets @uri's scheme to @scheme. This will also set @uri's port to the default port for @scheme, if known.
setUser void setUser(string user): Sets @uri's user to @user.
toString string toString(bool justPathAndQuery): Returns a string representing @uri.
usesDefaultPort bool usesDefaultPort(): Tests if @uri uses the default port for its scheme. (Eg, 80 for http.) (This only works for http, https and ftp; libsoup does not know the default ports of other protocols.)

Properties

fragment string fragment [@property getter]
string fragment [@property setter]: a fragment identifier within @path, or %NULL
host string host [@property getter]
string host [@property setter]: the hostname or IP address, or %NULL
password string password [@property getter]
string password [@property setter]: a password, or %NULL
path string path [@property getter]
string path [@property setter]: the path on @host
port uint port [@property getter]
uint port [@property setter]: the port number on @host
query string query [@property getter]
string query [@property setter]: a query for @path, or %NULL
scheme string scheme [@property getter]
string scheme [@property setter]: the URI scheme (eg, "http")
user string user [@property getter]
string user [@property setter]: a username, or %NULL

Static functions

decode string decode(string part): Fully %-decodes @part.
encode string encode(string part, string escapeExtra): This %-encodes the given URI part and returns the escaped version in allocated memory, which the caller must free when it is done.
getType GType getType()
normalize string normalize(string part, string unescapeExtra): %-decodes any "unreserved" characters (or characters in @unescape_extra) in @part, and %-encodes any non-ASCII characters, spaces, and non-printing characters in @part.

Variables

ownedRef bool ownedRef;: Undocumented in source.
soupURI SoupURI* soupURI;: the main Gtk struct

Meta

Source

See Implementation

soup URI classes

URI